home *** CD-ROM | disk | FTP | other *** search
/ Aminet 43 / Aminet 43 (2001)(GTI - Schatztruhe)[!][Jun 2001].iso / Aminet / comm / tcp / smbfs.readme < prev    next >
Text File  |  2001-05-03  |  21KB  |  462 lines
  1. Short:    SMB file system client; complements Samba
  2. Author:   Olaf Barthel (olsen@sourcery.han.de)
  3. Uploader: Olaf Barthel (olsen@sourcery.han.de)
  4. Version:  1.51
  5. Type:     comm/tcp
  6. Requires: Miami, Miami Deluxe, AmiTCP 3.x or AmiTCP Genesis
  7.  
  8.  
  9. A SMB file system wrapper for AmigaOS, using the AmiTCP V3 API
  10. ==============================================================
  11.  
  12. 1. What is it?
  13.  
  14. This document briefly describes the SMBFS program, which implements an SMB
  15. file system for AmigaOS. This file system can be used to access files made
  16. available by file servers which implement the SMB protocol, such as 'Microsoft
  17. Windows' or any other platform which supports the free 'Samba' product. These
  18. files can be accessed using shell commands such as 'List', the Workbench or
  19. utilities such as 'Directory Opus' as if the file server were a local disk
  20. drive.
  21.  
  22.  
  23. 2. What do you need to get started?
  24.  
  25. You need a TCP/IP stack that supports the AmiTCP V3 API, such as 'Miami', the
  26. original free 'AmiTCP 3.0' release, 'AmiTCP 4.x', 'Miami Deluxe' or 'AmiTCP
  27. Genesis' and the obligatory networking gear. All these items need to be in
  28. good shape and properly configured.
  29.  
  30. Most important, you need a computer which exports file sharing services using
  31. the SMB protocol.
  32.  
  33. It often helps to have 'Samba' installed on your Amiga, too, as this can aid
  34. in tracking down bugs and obtaining information which SMBFS cannot obtain all
  35. by itself.
  36.  
  37. Last but not least, you need to be proficient in configuring and using the
  38. TCP/IP stack; networking knowledge is definitely assumed.
  39.  
  40. SMBFS requires AmigaOS 2.04 or higher to work.
  41.  
  42.  
  43. 3. Preparations
  44.  
  45. You need to know which computer's files you want to share using the SMBFS file
  46. system. That computer must be known by name, it is not sufficient just to know
  47. its IP address. If you know the IP address but cannot refer to the host by its
  48. name then SMBFS will not work. In that case, make sure that you add a host
  49. name entry referring to the IP address to your TCP/IP stack's host database
  50. (e.g. the "AmiTCP:bin/hosts" file or the corresponding page in the stack's
  51. configuration user interface).
  52.  
  53. The name of the computer to connect to must not be too long. If it is longer
  54. than 16 characters, SMBFS will not work properly.
  55.  
  56. You need to know which service you want to connect to on the target computer.
  57. You can find out which services are available on a certain computer by using
  58. the Samba 'smbclient' program. For example, if you were to query the services
  59. offered by a machine called 'sourcery' you could enter the following:
  60.  
  61.    samba:bin/smbclient -L sourcery
  62.  
  63. And you might get the following information:
  64.  
  65.    added interface ip=192.168.0.1 bcast=192.168.0.255 nmask=255.255.255.0
  66.    Password: Domain=[ARBEITSGRUPPE] OS=[AmigaOS] Server=[Samba 2.0.7]
  67.  
  68.            Sharename      Type      Comment
  69.            ---------      ----      -------
  70.            All            Disk      All volumes in the system
  71.            IPC$           IPC       IPC Service (Amiga 3000UX)
  72.            olsen          Disk      Home Directories
  73.  
  74.            Server               Comment
  75.            ---------            -------
  76.            SOURCERY             Amiga 3000UX
  77.  
  78.            Workgroup            Master
  79.            ---------            -------
  80.            ARBEITSGRUPPE        SOURCERY
  81.    
  82. The share name to connect to would be "ALL" in this case.
  83.  
  84. You need to know which login name and which password are required to connect
  85. to the shared resource, and you need to know the name of the workgroup or
  86. domain the file server is a member of.
  87.  
  88.  
  89. 4. Starting and stopping the file system
  90.  
  91. SMBFS is an uncommon kind of file system in that you do not use the 'Mount'
  92. command to mount it. In fact, SMBFS is a shell program which can be launched
  93. from the shell, using command line parameters to tell it which resources
  94. should be used. But you can also start it from Workbench: in this case you
  95. would have to put the program's command line options into icon tool types.
  96.  
  97. By now you should have assembled the following information:
  98.  
  99.    - Name of the computer to connect to; this would be the
  100.      file server
  101.    - Name of the shared SMB resource to connect to
  102.    - Login name and password
  103.  
  104. That's basically everything you need to know to continue -- unless something
  105. goes wrong, but more on that lateron.
  106.  
  107. Now you can start the file system. For example, to connect to the file server
  108. called 'sourcery' and the shared 'all' resource it exports, with that computer
  109. being a member of the workgroup 'Arbeitsgruppe', using the login name
  110. 'PCGuest' and not providing any password you would enter the following:
  111.  
  112.    Run >NIL: SMBFS Workgroup=Arbeitsgruppe User=PCGuest Service=//sourcery/all
  113.  
  114. This would cause a new device by the name of "SMBFS:" to be mounted, showing
  115. all files and directories the 'sourcery' server makes available for sharing.
  116.  
  117. How do you 'unmount' the file system? That's very easy, just check the output
  118. of the 'Status' shell command. You might get the following output:
  119.  
  120.    Process  1: Loaded as command: TURBOTEXT
  121.    Process  2: Loaded as command: Work:Tools/Blowup
  122.    Process  3: Loaded as command: Work:Tools/Sashimi
  123.    Process  4: Loaded as command: Work:CyberTools/CyberGuard
  124.    Process  5: Loaded as command: Work:Tools/OpenDevicePatch
  125.    Process  6: Loaded as command: CED
  126.    Process  7: Loaded as command: Workbench
  127.    Process  8: Loaded as command: Status
  128.    Process  9: No command loaded
  129.    Process 10: Loaded as command: SMBFS '//sourcery/all'
  130.  
  131. Look at the last line describing process number 10: it shows the name of the
  132. file system program SMBFS and the name of the SMB share it is connected to. To
  133. stop this file system and effectively unmount it, use the shell 'Break'
  134. command; in this case you would enter "Break 10" to stop the file system. Note
  135. that the program may not terminate immediately; it may have to wait until the
  136. last client has released all resources referring to the file system. You may
  137. have to send more than one "Break" command to stop the program.
  138.  
  139.  
  140. 5. Startup options
  141.  
  142. The SMBFS program supports a number of command line options, as will be
  143. described below. The command template looks like this:
  144.  
  145.    DOMAIN=WORKGROUP/K,USER=USERNAME/K,PASSWORD/K,CHANGECASE/S,
  146.    CASE=CASESENSITIVE/S,OMITHIDDEN/S,QUIET/S,CLIENT=CLIENTNAME/K,
  147.    SERVER=SERVERNAME/K,DEVICE=DEVICENAME/K,VOLUME=VOLUMENAME/K,
  148.    CACHE=CACHESIZE/N/K,DEBUGLEVEL=DEBUG/N/K,TRANSLATE=TRANSLATIONFILE/K,
  149.    SERVICE/A
  150.  
  151. The individual options serve the following purposes:
  152.  
  153.    DOMAIN=WORKGROUP/K
  154.  
  155.       You must specify the name of the workgroup or domain the file server to
  156.       connect to is a member of. The name of this workgroup or domain must not
  157.       be longer than 16 characters. The name you provide will be translated to
  158.       all upper case characters.
  159.  
  160.       You need not provide for a work group or domain name on the command line.
  161.       Alternatively, you may configure an environment variable whose contents
  162.       will be used instead. The variable could be set up like this:
  163.  
  164.          SetEnv smbfs_workgroup <name of domain or workgroup>
  165.          Copy ENV:smbfs_workgroup ENVARC:
  166.  
  167.       You may also use the 'smbfs_domain' environment varilable in place of the
  168.       'smbfs_workgroup' variable. The two are aliases for one another, but
  169.       smbfs will read only one of the two.
  170.  
  171.    USER=USERNAME/K
  172.  
  173.       To connect to an SMB share you must authenticate yourself by providing a
  174.       user name. With this program the user name is optional; if you do not
  175.       provide one, SMBFS will use the default, which is "GUEST". The user name
  176.       must not be longer than 64 characters. The name you provide will be
  177.       translated to all upper case characters.
  178.  
  179.       You need not provide for a user name on the command line. Alternatively,
  180.       you may configure an environment variable whose contents will be used
  181.       instead. The variable could be set up like this:
  182.  
  183.          SetEnv smbfs_username <your user name>
  184.          Copy ENV:smbfs_username ENVARC:
  185.  
  186.       You may also use the 'smbfs_user' environment varilable in place of the
  187.       'smbfs_username' variable. The two are aliases for one another, but
  188.       smbfs will read only one of the two.
  189.  
  190.    PASSWORD/K
  191.  
  192.       As part of the authentication process required to make the connection to
  193.       an SMB share, you must provide for a user name and a password. The
  194.       password is optional; if you do not provide one, an empty password will
  195.       be transmitted. The password must not be longer than 64 characters.
  196.  
  197.       You need not provide for a password on the command line. Alternatively,
  198.       you may configure an environment variable whose contents will be used
  199.       instead. The variable could be set up like this:
  200.  
  201.          SetEnv smbfs_password <your password>
  202.          Copy ENV:smbfs_password ENVARC:
  203.  
  204.       Keep in mind that passwords like these really should not be exposed by
  205.       storing them in environment variables. But then the protocol smbfs uses
  206.       is almost as insecure as it gets anyway.
  207.  
  208.    CHANGECASE/S
  209.  
  210.       By default the password will not be changed to all upper case characters.
  211.       If this is required, you should either provide the password in this
  212.       form or resort to this option, which will cause it to be translated
  213.       to all upper case characters.
  214.  
  215.    CASE=CASESENSITIVE/S
  216.  
  217.       Some file servers treat file and directory names differently which
  218.       differ only in whether they are written using upper/lower case
  219.       characters. For these servers you should activate the CASESENSITIVE
  220.       switch to treat those files properly. There is a catch though: the
  221.       AmigaDOS file naming scheme does not follow this model and you may
  222.       run into problems when you are trying to use it. By default, the
  223.       file system does not treat file and directory names differently
  224.       which only differ with respect to the case of letters.
  225.  
  226.    OMITHIDDEN/S
  227.  
  228.       When requesting a directory listing, the server may return some files
  229.       and directories tagges as being hidden. By default this file system
  230.       will report these 'hidden' entries anyway, but you can request
  231.       specifically that what is intended to be hidden should be omitted
  232.       from directory listings, too. Note that even though a file may be
  233.       hidden you should still be able to open and examine it.
  234.  
  235.    QUIET/S
  236.  
  237.       When started from Shell, SMBFS will print a message as soon as the
  238.       connection to the file server has been established. If you do not
  239.       want to see that message displayed, use the QUIET parameter. Also,
  240.       no such message will appear if the program has been started to run
  241.       in the background.
  242.  
  243.    CLIENT=CLIENTNAME/K
  244.  
  245.       SMBFS will attempt to connect to the file server by providing the name
  246.       of the computer you connect from. In some cases this may be undesirable
  247.       as the computer's name differs from what the file server expects. You
  248.       can use the CLIENT parameter to tell SMBFS under which name it should
  249.       announce itself to the server. This parameter is optional and will be
  250.       translated to all upper case characters; it cannot be longer than 16
  251.       characters.
  252.  
  253.    SERVER=SERVERNAME/K
  254.  
  255.       SMBFS will attempt to connect to the file server by providing the name
  256.       you specified using the SERVICE command line parameter. In some cases
  257.       this may be undesirable as the server's name differs from what you
  258.       specified as the share name. You can use the SERVER parameter to tell
  259.       SMBFS under which name it should contact the server. This parameter is
  260.       optional and will be translated to all upper case characters; it cannot
  261.       be longer than 16 characters.
  262.  
  263.    DEVICE=DEVICENAME/K
  264.    VOLUME=VOLUMENAME/K
  265.  
  266.       The SMBFS program can announce itself as an AmigaDOS file system by
  267.       using one of two different methods.
  268.  
  269.       The first method involves announcing itself only as a file system
  270.       device. This should be sufficient in most cases but has a drawback in
  271.       that the device will not be usable from Workbench since the file system
  272.       will not appear as a disk icon. You tell SMBFS to use a specific device
  273.       name by using the DEVICE command line parameter, e.g. "DEVICE=SMBFS:".
  274.       Note that device names must be unique, i.e. there must be no other
  275.       device by the same name in the system; SMBFS will report an error and
  276.       exit if it finds one.
  277.  
  278.       The second method involves announcing itself as a volume. This has the
  279.       benefit of making the file system usable from Workbench since a disk
  280.       icon will appear for it. You tell SMBFS to use a specific volume name by
  281.       using the VOLUME command line parameter, e.g. "VOLUME=Sourcery:".
  282.  
  283.       Both methods have advantages and drawbacks. The drawback of the VOLUME
  284.       method is that it may deadlock the native Amiga Samba port as soon as
  285.       the file system is mounted. The drawback of the DEVICE method is that
  286.       the file system will not be usable from Workbench.
  287.  
  288.       If you wish, you can combine both methods; this is the approach most
  289.       other file systems use. And in fact, when you tell SMBFS to add a
  290.       volume it will also add a device to go along with it.
  291.  
  292.       The VOLUME and DEVICE keywords are optional; if you omit both, SMBFS
  293.       will pretend that you had used the "DEVICE=SMBFS:" parameter.
  294.  
  295.    CACHE=CACHESIZE/N/K
  296.  
  297.       The file system attempts to optimize accesses to the file server when
  298.       directory contents are being scanned. These contents are buffered in
  299.       a directory cache which by default will hold 170 entries. Since each
  300.       entry will require about 255 bytes of storage, the entire 170 entry
  301.       cache will occupy more than 40K bytes of memory. You may want to change
  302.       this requirement, by making the cache smaller or larger using the
  303.       CACHESIZE parameter. The size of the directory cache cannot be smaller
  304.       than 10 entries.
  305.  
  306.    DEBUGLEVEL=DEBUG/N/K
  307.  
  308.       By default SMBFS operates in silent mode. It does not report what it is
  309.       doing, it just tries to respond to file system requests. To obtain
  310.       debugging output you may want to use the DEBUG option and specify a
  311.       debug level greater than 0. The larger the number you specify the more
  312.       debugging output will be created. Note that all debugging output will be
  313.       produced using the operating system's debug output functionality which
  314.       requires that you have a capturing program like 'Sashimi' running in the
  315.       background.
  316.  
  317.    TRANSLATE=TRANSLATIONFILE/K
  318.  
  319.       The Amiga and the file server SMBFS connects to may not share the same
  320.       character set. International characters used in file names on either
  321.       side may not come out correctly on the other side. To remedy this
  322.       problem, you can resort to file name translation. How the individual
  323.       names are to be translated is determined by the contents of a file
  324.       name translation table file such as the ones that ship with Workbench
  325.       in the "L:FileSystem_Trans" drawer. The first 256 bytes of each such
  326.       file must consist of the mapping of Amiga characters to the different
  327.       character set, and the second 256 characters must describe a mapping
  328.       back from the different character set to the Amiga. In most cases the
  329.       "L:FileSystem_Trans/INTL.crossdos" translation table file should be
  330.       sufficient. To specify which file contains the translation tables to
  331.       use you would use the TRANSLATIONFILE parameter.
  332.  
  333.    SERVICE/A
  334.  
  335.       This is the last parameter to be specified on the command line. It
  336.       should refer to the file server you want to connect to and the resource
  337.       it exports, e.g. a file system. This parameter must start with two
  338.       slashes which must be immediately followed by the file server's name,
  339.       which must be followed by the resource to connect to.
  340.  
  341. The same parameters are also used when starting SMBFS from Workbench. SMBFS
  342. will examine its icon tool types and use these in place of the shell command
  343. line.
  344.  
  345.  
  346. 6. Known problems
  347.  
  348. The design of smbfs follows the original file system concept behind the
  349. code which the 'Sharity-Light' file system is based upon. And that is a
  350. Unix file system which differs from Amiga specific file systems in many
  351. ways which can lead to problems which are discussed briefly below:
  352.  
  353.    - Single threaded design
  354.  
  355.      This means that it is not possible for several programs to fairly
  356.      share the use of the file system. For example, a program that posts
  357.      a long read request can tie up the file system almost exclusively
  358.      for itself, and while it is busy all other clients will have to
  359.      wait. Same goes for directory scanning.
  360.  
  361.    - Poor scalability
  362.  
  363.      This is associated with the single threaded design. When several
  364.      programs are accessing the file system at the same time, overhead
  365.      and unfair sharing of resources will drastically reduce the
  366.      performance of the file system.
  367.  
  368.    - Separation of file data and metadata
  369.  
  370.      This means that the core of the file system treats the contents of
  371.      a directory and the data attached to each file inside that
  372.      directory as something different. This is a common concept with
  373.      Unix file systems, but it is very different with Amiga file systems.
  374.      In smbfs this data separation can cause problems when deleting
  375.      files from a directory while that directory is being scanned,
  376.      such as how this is being done by the 'Delete' shell command. The
  377.      effects of these problems are that a directory may not be deleted
  378.      even though it is empty or that for the same directory the same
  379.      file may be reported twice in the listing.
  380.  
  381. While there are no easy solutions for any of these problems, it does not
  382. mean that smbfs is unusable. You just have to be more careful when you
  383. use the file system. For example, if a directory's contents cannot be
  384. deleted due to one of the problems mentioned above, you might want to
  385. retry later.
  386.  
  387. It should be noted that the problems described above are not inherent
  388. to the original file system design. It's just that transferring that
  389. design to an Amiga file system created the problems.
  390.  
  391.  
  392. 7. Credits
  393.  
  394. This file system is based upon prior work by Paal-Kr. Engstad, Volker
  395. Lendecke, Mark A. Shand, Donald J. Becker, Rick Sladkey, Fred N. van Kempen,
  396. Eric Kasten and Rudolf Koenig. It is a direct descendant of the
  397. 'Sharity-Light' file system written by Christian Starkjohann.
  398.  
  399. The password encryption code was lifted from the Samba package. It was
  400. written by Andrew Tridgell and the Samba Team.
  401.  
  402.  
  403. 8. Author
  404.  
  405. The 'Sharity-Light' source code was adapted and wrapped into an AmigaOS layer
  406. by Olaf `Olsen' Barthel. If you wish to contact me, please send e-mail to the
  407. following address:
  408.  
  409.    olsen@sourcery.han.de
  410.  
  411. Or, alternatively, you might want to contact me via my postal address:
  412.  
  413.    Olaf Barthel
  414.    Brabeckstr. 35
  415.    D-30559 Hannover
  416.    Federal Republic of Germany
  417.  
  418. If you want to submit a bug report or an enhancement request, please enclose
  419. sufficient information to allow me to make sense of the problem. That includes
  420. debugging logs produced using the DEBUG option.
  421.  
  422.  
  423. 9. Source code
  424.  
  425. SMBFS is distributed under the terms of the GNU General Public License
  426. (version 2). The source code should have accompanied this program; if it
  427. hasn't, please contact the author for a copy.
  428.  
  429. The program was compiled using the SAS/C 6.58 compiler, with the Miami SDK
  430. providing for the TCP/IP stack API header files.
  431.  
  432.  
  433. ============================= Archive contents =============================
  434.  
  435. Original  Packed Ratio    Date     Time    Name
  436. -------- ------- ----- --------- --------  -------------
  437.    12489    4966 60.2% 13-Mar-01 18:46:02  history.doc
  438.    50888   28315 44.3% 07-Apr-01 12:28:04  smbfs
  439.    19207    6870 64.2% 03-Mar-01 16:16:34  smbfs.doc
  440.     7148    2038 71.4% 07-Jan-01 10:04:10 +assert.c
  441.     4139    1368 66.9% 07-Jan-01 10:04:16 +assert.h
  442.    17982    6993 61.1% 04-May-96 02:50:42 +COPYING
  443.    17250    5316 69.1% 17-Dec-00 10:39:34 +crypt.c
  444.     2211     982 55.5% 11-Dec-00 18:48:16 +smb.h
  445.     3050     789 74.1% 28-Nov-00 10:59:18 +smb_fs.h
  446.     1217     603 50.4% 04-Dec-00 17:05:02 +smb_fs_sb.h
  447.      563     358 36.4% 02-Dec-00 14:04:58 +smb_mount.h
  448.    11723    3365 71.2% 31-Oct-00 17:30:56 +smbno.h
  449.   115850   28238 75.6% 07-Apr-01 12:32:28 +main.c
  450.    64200   17138 73.3% 28-Dec-00 16:04:42 +proc.c
  451.     4050    1475 63.5% 04-Mar-01 10:08:06 +smakefile
  452.    33067    7686 76.7% 28-Dec-00 16:05:14 +smb_abstraction.c
  453.     2126     770 63.7% 03-Dec-00 14:50:10 +smb_abstraction.h
  454.      188     109 42.0% 13-Mar-01 18:38:22 +smbfs_rev.h
  455.      234     122 47.8% 13-Mar-01 18:38:22 +smbfs_rev.i
  456.        3       3  0.0% 13-Mar-01 18:38:22 +smbfs_rev.rev
  457.    11363    2710 76.1% 03-Feb-01 16:17:40 +sock.c
  458.     1098     605 44.8% 07-Jan-01 10:04:38 +system_headers.c
  459.     3208    1054 67.1% 07-Jan-01 10:04:44 +system_headers.h
  460. -------- ------- ----- --------- --------
  461.   383254  121873 68.2% 08-Apr-101 23:12:12   23 files
  462.